docs: define hierarchical pty contract - #148

Owner review: please keep this draft and reduce it before further review. Target the smallest useful V/R/S shape: one concise vision/purpose source, one requirement set, and one specification that links each retained term and constraint to the source that owns it and to its validating tests. Remove the repeated per-node intuition.md/ontology.md trees and the 74-ID refinement hierarchy unless a concrete consumer requires them. Split src/server.ts, src/spawn.ts, and any public error or documentation wording changes into a separate PR unless a retained contract requirement strictly requires those changes. Converge dependencies with normal merges after they land; do not restack or rewrite shared history. Please return the reduced file list and requirement count with validation receipts; leave #148 draft.

Addressed in f89f758 plus normal merges of current main (current head b2e2ff0).

The PR is now reduced to four files:

• README.md — one VRS discoverability link
• docs/vrs/requirements.md — 11 requirements
• docs/vrs/spec.md — the single contract, with owning-source and executable-test links for every requirement
• scripts/verify-docs.ts — minimal two-document/ID/reference/link validation

Removed all 30 hierarchy/intuition/ontology files and all changes to DEVELOPMENT, public API docs, source JSDoc, public error wording, and runtime code. README remains the concise purpose source; there is no vision.md.

Receipts:

• VRS check: 2 documents / 11 IDs, passed
• build: passed
• typecheck: passed
• diff check: passed
• final diff: 4 files / 343 additions

I created backup/2026-07-31-pty-vrs-pre-owner-reduction, merged current main normally (no restack/rewrite), and kept #148 draft. It still waits on #146 and #147; after both land I will merge main normally again and validate the final composed contract.

Actually, I think we should bring back the hierarchical VRS structure unless you disagree @myobie ?

Final composition receipt after the owner-requested reduction:

• fix: frame intentional machine detach outcomes #146 merged as a1f8236; fix: replace same-socket client roles explicitly #147 merged as 7effe7b.
• Both were integrated by normal merges from current main; no restack or rewrite.
• Final docs: define hierarchical pty contract #148 head: 9daf3331a5500629388f22c855ca1ae3570e164f.
• Final diff remains 4 files, 2 VRS documents, and 11 requirements.
• Focused composed behavior: 80/80 tests passed (integration.test.ts + attach-stream.test.ts).
• VRS shape/IDs/links, build, typecheck, and diff check all passed.

#148 remains ready. Fresh hosted checks for this exact final head are now pending; I will report them separately rather than claiming them early.

Final owner-review receipt after both runtime dependencies merged:

• exact head: 9daf3331a5500629388f22c855ca1ae3570e164f
• exact base: 7effe7b8c4ee22796f62188d321445027c8f5096 (contains test: make broken attach stream fixture protocol-valid #145, fix: frame intentional machine detach outcomes #146, and fix: replace same-socket client roles explicitly #147)
• final diff: 4 files / 343 additions
• VRS shape: 2 documents / 11 requirements
• local composed proof: integration + attach-stream 80/80; VRS/build/typecheck/diff green
• hosted Nix: run 30661405757, success
• hosted Vitest: run 30661405727, success
• GitHub: ready, CLEAN, MERGEABLE

The repeated hierarchy and unrelated source/public wording changes are gone. This is ready for your review.

Exact-head hosted receipt for 9daf3331a5500629388f22c855ca1ae3570e164f:

• Nix build: SUCCESS
• Test vitest: SUCCESS
• PR state: ready, CLEAN, MERGEABLE

This confirms the final composed branch after both #146 and #147 merged.

Thank you, Nathan, for the careful design guidance and review — the smaller contract is much stronger for it. Celebrating this one!